/*******************************************************************************
 * Copyright 2011 @ Kapil Viren Ahuja
 * 
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 * 
 *   http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 ******************************************************************************/
package com.kapilvirenahuja.eamsteps.dataprovider;

import com.kapilvirenahuja.eamsteps.datareader.IDataSet;
import com.kapilvirenahuja.eamsteps.datareader.excel.ExcelDataSet;
import com.kapilvirenahuja.eamsteps.form.IDataForm;

/**
 * Interface defining a data provider. This Interface provides a contract between two objects:
 * <ul>
 * <li><b>DataSet</b>: A dataset is an implementation of {@link IDataSet} which acts as the provider from where the data
 * is to be read. You can look at the {@link ExcelDataSet} as one of the implementations which reads the data from an
 * underlying Excel workbook using JExcel APIs.</li>
 * <li><b>Form</b>: A form is a Java Object that implements {@link IDataForm} that will hold the data in memory for 
 * classes to consume it later.</li>
 * </ul>
 * 
 */
public interface IDataProvider
{
    /**
     * <p>
     * Reads the data from the underlying {@link IDataSet}.
     * </p>
     * 
     * <p>
     * Data Provider should have a valid {@link IDataForm} and a valid {@link IDataSet} before it can proceed with reading data. If
     * the <code>validateForm</code> has not been executed, this method will first validate the form.
     * </p>
     * 
     * @return Initialized Java object with the data.
     */
    IDataForm readData();


    /**
     * Validate the Form. The data provider should be have a valid form in order to proceed with readData.
     * 
     */
    void validateForm();


    /**
     * Retrieve the underlying data set.
     */
    IDataSet getDataSet();

    
    /**
     * Sets an object of {@link IDataSet} on the class.
     * 
     */
    void setDataSet(IDataSet dataSet);

    /**
     * Retrieve the underlying form.
     */
    Object getForm();
    
    
    /**
     * Returns <code>true</code> is the underlying validations pass, else returns <code>false</code>. The code
     * execution should be halted in case the validations fail.
     * 
     */
    Boolean isValid();
    
}
